TPUG - Toronto PET Users Group/TPUG Users Group CD/TPUG Users Group CD.iso/AMIGA/AMICUS/AMICUS25.ADF/KeyBird/keybird.doc

Text File | 1989-01-26 | 17KB | 287 lines

Keybird--the Keyboard Enhancer.   Version 1.0
  by Michael A. Ingrassia, Amicus/H.V.

Keybird is a keyboard enhancer.  It enables you to define (and redefine)
your own keymaps, and is the first keyboard enhancer I know of to enable
you to load any system keymap and make ANY modifications you want.  Here is
a brief run-through of the program's features.

DEFAULT KEYMAP
  When the program starts, a practically useless keymap is preloaded.
In this keymap (which has no name), no keys are defined.  It is useful
for people who want to start completely from scratch; at any point this
"blank slate" can be reinstated by selecting "New" from the "Keybird
Projects" menu.  But most of us want to tinker with a pre-existing
keymap.  So your first action should be to select "Load Keymap" from the
"Keybird Projects" menu.  The program's default selection for you to load
is "usa2", which is a Dvorak keyboard.  Another possibility, almost surely
in your devs:keymaps directory, is "usa0", the keymap which was standard
under Workbench 1.1.  Unfortunately, the keymap standard for Workbench
1.2, "usa", is in ROM (or WCS), and so does not usually appear in
devs:keymaps.  This is no problem; the file "Thisisusa" with this
distribution is actually the usa keymap, as relocated and transcribed from
ROM.  Just make sure it's copied into devs:keymaps before running
keybird.  After loading it, you are ready to start making modifications.

CAPSABLE KEYS
  The program starts you on the Capsable Screen. Each physical key has
associated with it in a keymap a bit which makes it either capsable or
not capsable.  The distinction is this:  a capsable key produces a shifted-
character when the Caps Lock key is lit, a noncapsable key does not.
It is important to realize that the Caps Lock key is not the same as a
Shift Lock key!!  For example, the "a" key produces "A" when Caps Lock
is lit, while the "/" key continues to produce "/"--to get "?" you MUST
use a shift key in combination with the "/" key.  On the Capsable Screen,
the status of each key is shown.  In the "usa" keymap, only the alphabetic
characters are capsable--they are shown in RED.  Non-capsable keys are
shown in BLUE.  To change the status of a key, click on the key using
the mouse--its color lightens, to show it is highlighted.  Now click on
the box marked "Make Capsable" or "Make Not Capsable"--watch the color
of the highlighted key change.

REPEATABLE KEYS
  To reach the Repeatable Screen, click on the Repeatable gadget in the
lower left.  Each physical key has associated with it in a keymap a bit
which makes it either repeatable or not repeatable.  A repeatable key
repeats when it is held down sufficiently long; a non-repeatable key must
be re-struck.  For example, in the "usa" keymap the "a" key is repeatable
and the <Return> key is not repeatable.  (To test these assertions, be
sure you are in a situation in which a keymap is being consulted--for
example, in a CLI window, but NOT in the AmigaBasic editor!)  Non-repeatable
keys are shown in BLUE.  Repeatable keys are shown in RED.  To change
the status of a key, select the key by clicking on it, then click on the
"Make Repeatable" or "Make Not Repeatable" gadget and watch the key's
color change.

DEADKEYS SCREEN
  To reach the Deadkeys Screen, click on the Deadkeys gadget in the lower
left.  To see what a deadkey is, in a CLI window try typing Alt-f.  The
cursor does not appear to move.  Now type "a". You obtain an accented "a"!
The "usa" keymap has 10 deadkeys: Alt-f, Alt-g, Alt-h, Alt-j, Alt-k,
Alt-F, Alt-G, Alt-H, Alt-J, and Alt-K. Try typing each of them, following
each immediately with the spacebar.  It is important to realize that you
are not actually typing a grave accent (or whatever) when you type a
deadkey.  Rather, the console device remembers that you have typed a
deadkey and outputs no value yet (that's why the cursor doesn't move).
If you now type a MODIFIABLE key, the console device consults the keymap
to find out how to render the particular deadkey-modifiable key
combination.  If instead you followed the deadkey with a non-modifiable
key, the deadkey is discarded and the non-modifiable key is used by itself.
For example, in the "usa" keymap, Alt-j seems to be a tilde.  (Try
Alt-j, <spacebar> in your CLI window.)  Actually, it is a deadkey.
Alt-j followed by <spacebar> gives a tilde because <spacebar> is a
modifiable key, and there is a table in the keymap to show how to render
the Alt-j (deadkey)--<spacebar> (modifiable) combination.  Alt-j followed
by "i" produces just an "i"--because that's the value in the keymap for
the Alt-j (deadkey)--<spacebar> (modifiable) combination.  Alt-j followed
by "m" produces just "m"--because "m" is not a modifiable key and so
the pending Alt-j is discarded when the "m" is struck.  There is no reason
why Alt-j followed by "i" could not give "j"--just define it that way
in keybird!
   Note that while Alt-j is a deadkey, "j" by itself is not.  Whereas
a physical key is either Capsable or not, each particular way of qualifying
a key could give a deadkey or not.  So in the Deadkeys Screen (as also in
the Modifiable Screen and the Keymap Screen, but not in the Capsable
Screen or the Repeatable Screen) the qualifier gadgets in the upper right
of the display are active.

QUALIFIERS
   There are four possible qualifiers: Shift, Alt, Control, and Downup.
The first three are straightforward.  Normally both shift keys act the
same, as do both Alt keys.  A "j" key can be qualified in 8 ways by the
3 keys: you can produce "j" (alone), Shift-j, Alt-j, Shift-Alt-j,
Control-j, Control-Shift-j, Control-Alt-j, and Control-Shift-Alt-j.  Each
of these qualified keys can be mapped to a different code or string.
Downup is a little unusual--the Amiga allows you to assign  different
codes to the up-down transition of a key, the key depress (usual case) and
to the down-up transition of a key, the key release.  In the "usa" keymap,
no keys produce down-up codes.  In the "color" keymap, supplied with
this distribution, the keypad keys produce downup-transitions.  Try
depressing "1" on the keypad, then WITHOUT RELEASING IT, type a message
with your left hand in the CLI window.  As you type, release the "1" key
on the keypad and see what happens.  Depressing and releasing the "1" key
without typing any intervening letters seems to have no effect.  That's
because the "1" key is actively qualified by the Downup qualifier.  It's
hard to imagine too many uses for the Downup transition--but keybird will
give your imagination full reign to work!
     So the 16 possible qualifier states for a key are:
        alone                           downup
        shift                           downup-shift
        alt                             downup-alt
        shift-alt                       downup-shift-alt
        control                         downup-control
        control-shift                   downup-control-shift
        control-alt                     downup-control-alt
        control-shift-alt               downup-control-shift-alt
     The keyboard reflects the current state of keys AS QUALIFIED BY THE
ACTIVE (RED) QUALIFIERS in the upper right of the display.  For example,
in the Deadkeys Screen, click on the ALT gadget on the upper right.
AL should now be RED (active), and "DO" (=Downup),"CT" (=Control), and
"SH" (=Shift) should be BLUE (inactive).  Assuming we are back to the
"usa" keymap, you will find for example that the "f","g","h","j",and "k"
keys are RED--that's because Alt-f, Alt-g, Alt-h, Alt-j, and Alt-k are
deadkeys.  The "a" key is BLUE--that's because Alt-a is not a deadkey.
The <period> key is BLACK--that's because the <period> key is not
actively qualified by the Alt key.  Alt-period gives a period, true, but
only because the <period> key ignores the Alt qualifier.  In general,
keys on the Deadkeys, Modifiable, and Keymap screens are BLACK if they are
not actively qualified by (separately defined for) the particular
combination of qualifiers displayed in the upper right of the display.
Since the "usa" keymap has no definitions for down-up transitions, for
example, whenever the "DO" gadget in the upper right is active (RED), all
of the keys will be BLACK (inactive).  Only in the Keymap screen can the
status of a key switch from active (red or blue) to inactive (black) or
vice versa.
   Note that at any time (except in the Capsable and Repeatable Screens)
you can change the current qualifier combination you are working with.
There are three ways to do this.  First, you can click on the qualifier
gadgets in the upper right to achieve exactly the combination you want.
Just remember that RED means active, BLUE means inactive.  (Why not
black for inactive? I don't know.) Second, you could instead click on the
"Cycle Qualifiers" gadget in the lower right.  This cycles you through all
16 combinations of Downup,Control,Alt,Shift on or off.  This is more
convenient than the first method if you just want to see all the
keys under all qualifier combinations, perhaps to locate all the deadkeys
in a given unfamiliar keymap.  However, if you are working with a
particular key, which has been highlighted (by clicking on it), and that
key is actively qualified by (say) Control only, then you may prefer
the Third method: click on the "Cycle Active Qualifiers" gadget in the
lower right.  This will take you through only those qualifier combinations
which are separately defined in the keymap for the highlighted key.
For example, in the "usa" keymap the <return> key is active only with
the Control qualifier.  Shift-return is the same as <return>, because
the shift qualifier is ignored.  To define shift-return as something new,
you would have to first create a space for a separate definition of
shift-return, by making shift-return active, then create your definition.
   Note that it is possible to redefine the shift key, for example,
by making it active and then giving a definition for it!  Then, every time
you hit the shift key, you would get your new code as well as the codes
for any keys you qualify with the shift key by depressing at the same time.

MODIFIABLE SCREEN
   Modifiable (qualified) keys are RED.  Non-modifiable keys are BLUE.
Non-active keys are BLACK.  In the "usa" keymap, there are 15 modifiable
keys: "a", "e", "i","o","u","y","n",<spacebar>,Shift-a, Shift-e, Shift-i,
Shift-o, Shift-u, Shift-y, Shift-n .  Each of these keys can be given
a separate definition for every deadkey.  To make an active key modifiable
or non-modifiable, click on it with the mouse and then click on the
"Make Modifiable" or "Make Not Modifiable" gadget.
   Exercise: define Shift-return to be a deadkey (after making it active),
and define Shift-spacebar to be a modifiable key (after making it active).
Shift-return followed by Shift-spacebar should give "j".

KEYMAP SCREEN
  Active keys are RED or BLUE.  Inactive keys are BLACK.  To make a key
active, highlight it by clicking on it with the mouse, then click on the
"Make Active" gadget.  To make a key inactive, highlight it by clicking
on it with the mouse, then click on the "Make Not Active" gadget.  But note
that if the current qualifier state is Control-Shift, say, as determined
by checking the gadgets in the upper right ("DO" and "AL" blue, "CO" and
"SH" red), then it is impossible to make a key inactive because keybird
doesn't know whether you want to eliminate the possibility of Control
affecting your key or the possibility of Shift affecting your key. (If
Control and Shift each separately affect your key, you MUST provide a
definition for the Control-Shift combination).
   A key is normally red if some qualification of that key produces a
string; blue if all qualifications of the key produce a single byte.

IMPORTANT NOTE
   Because of a limitation in the keymap definition, any key which
controls a deadkey or a modifiable key MUST be defined to produce only
a single byte, no matter how it is qualified.  For example, in the "usa"
keymap, we cannot redefine the "f" key to give the string "filenote",
even though the "f" key is an ordinary key, because there is a qualification
of the "f" key, namely Alt-f (or Shift-Alt-f),  which is a deadkey.

DEFINING KEYS
   Subject to the limitation noted above, a key can be redefined in any
Screen (Capsable, Repeatable, Deadkeys, Modifiable, Keymap), except that
qualified keys cannot be redefined in the Capsable or Repeatable Screens
because there the qualifier combination is always taken to be "alone".
To redefine it, just type your proposed new definition on the keyboard.
It appears in the text box next to the label "New:".  To enter the
definition into the keymap you are building, type <return>.  The
<Backspace> key (or Control-H) is active so you can correct your
definition if you make a mistake.
   Most control-keys can be entered by typing the control-combination
itself.  So, to enter Control-a, just type Control-a.  There are two
obvious exceptions: Control-h is active as a backspace and Control-m
as a return.  Control-C is NOT an exception.  There is a non-obvious
exception--Control-S suspends the program.  Type any other key to wake
the program up.  This can be very mysterious!  Note that Control-a
appears in the textbox as a BLUE "A".  Grey letters are non-control
characters; blue letters are control characters (codes in the range 0-31).
A string of characters should be 32 characters or fewer in length.
The "blue" convention enables us to guarantee to be able to display all
32 characters no matter how many imbedded control characters there are.
   To type a high control character (codes in the range 128-159), type
the <help> key and then type an alphabetic character.  For example,
<help> followed by "a" gives High-Control-a (Control-a with high bit set).
<help> can be combined with "@","[","]","\" in addition to alphabetic
characters.  High-control-characters show up in RED.
  In sum: Control-characters are in BLUE.
          High-Control-characters are in RED.
          Ordinary characters are in GREY.
  Oh yes--if you want a Control-S, type <help> followed by ( with) Shift-S.
  To get Control-M,                type <help> followed by         Shift-m.
  To get Control-H,                type <help> followed by         Shift-h.
  To get Control-C,                type Control-C or
                                   type <help> followed by         Shift-c.
  Exercise: redefine Alt-d to be the string "dir^M" so that typing
Alt-d at a CLI prompt will automatically give you a directory.

SAVING YOUR KEYMAP
  Just select "Save" from the "Keybird Projects" menu and follow
directions.   You get an icon with your keymap which you can delete from
the CLI later, as it is useless.

INSTALLING YOUR KEYMAP
  Suppose your keymap has been saved to devs:keymaps under the name "foo".
Then the CLI command "setmap foo" will install your keymap.  Any program
launched from this CLI which normally inherits the "usa" keymap from the
CLI will now inherit "foo" instead. Alternatively, you can double click
on the "setmap" icon (in the System drawer of your Workbench disk"
after setting "keymap=foo" in the Tools line of the display obtained by
selecting the "setmap" icon and choosing the "Info" option from the
Workbench menu.

RESOURCES
   Please note that a keymap is a resource.  That is, once installed, the
system expects it not to change.  Suppose you create "foo", save it,
install it, then notice that you forgot to redefine some key.
You re-enter keybird, load "foo", change it, save it back to devs:keymaps,
and reinstall it, only to find no apparent change from the earlier version.
That is because the system responds to your second attempt to install "foo",
in effect, by saying "Hmmm...I don't need to load "foo" from devs:keymaps
because I've already got a "foo" in memory and one "foo" is as good as
another."  This will happen even if you try the sequence "setmap usa" and
then "setmap foo", because the system is very tenacious about holding on
to resources.  "No sense dumping this "foo" keymap I've got in memory, even
though nobody's using it anymore, because somebody may want it later--son of
a gun, sure enough, here's somebody who wants "foo" again!"  It is pretty
easy (although I haven't done it) to write a quicky program to flush the
system of all keymaps not in use--or you could just rename your works in
progress "foo1","foo2", etc.

DISTRIBUTION
   This version 1.0 is fairly clunky, because it was developed in and still
runs in interpreted basic.  Anyone interested in seeing improvements to the
the program, including but not limited to compilation or rewrite in "c",
and elimination of remaining bugs,  is invited to write (or send money) to
      Michael A. Ingrassia
      Dept. of Mathematics and Computer Science
      SUNY--College at New Paltz
      New Paltz, NY 12561
The program is copyright (c) 1987 by Michael A. Ingrassia, Amicus/HV.  All
    rights reserved.
Licensed for non-commercial distribution (freeware).
Please feel free to share the program as much as you want.  If you
modify it, please send me notice of your modifications and do not remove
the original copyright notice.